<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>lio_listio</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_362">&nbsp;</a>NAME</h4><blockquote>
lio_listio - list directed I/O
(<b>REALTIME</b>)
</blockquote><h4><a name = "tag_000_007_363">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="aio.h.html">aio.h</a>&gt;

int lio_listio(int <i>mode</i>, struct aiocb * const <i>list</i>[], int <i>nent</i>,
    struct sigevent *<i>sig</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_364">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>lio_listio()</i>
function allows the calling process to initiate
a list of I/O requests with a single function call.
<p>
The
<i>mode</i>
argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in
<i><a href="aio.h.html">&lt;aio.h&gt;</a></i>
and determines whether the function returns
when the I/O operations have been completed,
or as soon as the operations have been queued.
If the
<i>mode</i>
argument is LIO_WAIT,
the function waits until all I/O is complete and the
<i>sig</i>
argument is ignored.
<p>
If the
<i>mode</i>
argument is LIO_NOWAIT,
the function returns immediately,
and
asynchronous notification
occurs, according to the
<i>sig</i>
argument, when all the I/O operations complete.
If
<i>sig</i>
is NULL, then no asynchronous notification occurs.
If
<i>sig</i>
is not NULL, asynchronous notification occurs as specified in
<xref href=siggendel><a href="sigaction.html#tag_000_008_581_001">
Signal Generation and Delivery
</a></xref>
when all the requests in
<i>list</i>
have completed.
<p>
The I/O requests enumerated by
<i>list</i>
are submitted in an unspecified order.
<p>
The
<i>list</i>
argument is an array of pointers to
<b>aiocb</b>
structures.
The array contains
<i>nent</i>
elements.
The array may contain NULL elements,
which are ignored.
<p>
The
<i>aio_lio_opcode</i>
field of each
<b>aiocb</b>
structure specifies the operation to be performed.
The supported operations are
LIO_READ, LIO_WRITE and LIO_NOP;
these symbols are defined in
<i><a href="aio.h.html">&lt;aio.h&gt;</a></i>.
The LIO_NOP operation causes the list entry to be ignored.
If the
<i>aio_lio_opcode</i>
element is equal to LIO_READ,
then an I/O operation is submitted as if by a call to
<i><a href="aio_read.html">aio_read()</a></i>
with the
<i>aiocbp</i>
equal to the address of the
<b>aiocb</b>
structure.
If the
<i>aio_lio_opcode</i>
element is equal to LIO_WRITE,
then an I/O operation is submitted as if by a call to
<i><a href="aio_write.html">aio_write()</a></i>
with the
<i>aiocbp</i>
equal to the address of the
<b>aiocb</b>
structure.
<p>
The
<i>aio_fildes</i>
member specifies the file descriptor on which the operation
is to be performed.
<p>
The
<i>aio_buf</i>
member specifies the address of the buffer to or from
which the data is to be transferred.
<p>
The
<i>aio_nbytes</i>
member specifies the number of bytes of data to be transferred.
<p>
The members of the
<i>aiocb</i>
structure further describe the I/O operation to be performed,
in a manner identical to that of the corresponding
<b>aiocb</b>
structure when used by the
<i><a href="aio_read.html">aio_read()</a></i>
and
<i><a href="aio_write.html">aio_write()</a></i>
functions.
<p>
The
<i>nent</i>
argument specifies how many elements are members of the list,
that is, the length of the array.
<p>
The behaviour of this function is altered
according to the definitions of
synchronised I/O data integrity completion and
synchronised I/O file integrity completion.
if synchronised I/O is enabled on the file associated with
<i>aio_fildes</i>.
<p>
For regular files, no data transfer will occur past the offset maximum
established in the open file description associated with
<i>aiocbp-&gt;aio_fildes</i>.
</blockquote><h4><a name = "tag_000_007_365">&nbsp;</a>RETURN VALUE</h4><blockquote>
If the
<i>mode</i>
argument has the value LIO_NOWAIT,
the
<i>lio_listio()</i>
function returns the value zero
if the I/O operations are successfully queued;
otherwise, the function returns the value -1 and sets
<i>errno</i>
to indicate the error.
<p>
If the
<i>mode</i>
argument has the value LIO_WAIT,
the
<i>lio_listio()</i>
function returns the value zero
when all the indicated I/O has completed successfully.
Otherwise,
<i>lio_listio()</i>
returns a value of -1 and sets
<i>errno</i>
to indicate the error.
<p>
In either case, the return value only indicates
the success or failure of the
<i>lio_listio()</i>
call itself, not the
status of the individual I/O requests.
In some cases one or more of the I/O requests contained in the list may fail.
Failure of an individual request does not prevent completion of any other
individual request.
To determine the outcome of each I/O request,
the application examines the error status associated with each
<b>aiocb</b>
control block.
The error statuses so returned
are identical to those returned as the result of an
<i><a href="aio_read.html">aio_read()</a></i>
or
<i><a href="aio_write.html">aio_write()</a></i>
function.
</blockquote><h4><a name = "tag_000_007_366">&nbsp;</a>ERRORS</h4><blockquote>
The 
<i>lio_listio()</i>
function will fail if:
<dl compact>

<dt>[EAGAIN]<dd>
The resources necessary to queue
all the I/O requests were not available.
The application may check
the error status for each
<b>aiocb</b>
to determine the individual request(s) that failed.

<dt>[EAGAIN]<dd>The number of entries indicated by
<i>nent</i>
would cause the systemwide limit AIO_MAX to be exceeded.

<dt>[EINVAL]<dd>
The
<i>mode</i>
argument is not a proper value,
or the value of
<i>nent</i>
was greater than AIO_LISTIO_MAX.

<dt>[EINTR]<dd>
A signal was delivered
while waiting for all I/O requests to complete during a
LIO_WAIT operation.
Note that, since each I/O operation invoked by
<i>lio_listio()</i>
may possibly provoke a signal when it completes,
this error return may be caused by the completion of one (or more) of the
very I/O operations being awaited.
Outstanding I/O requests are not canceled,
and the application examines each list element
to determine whether the request was initiated, canceled, or completed.

<dt>[EIO]<dd>
One or more of the individual I/O operations failed.
The application may check the error status for each
<b>aiocb</b>
structure to determine the individual request(s) that failed.

<dt>[ENOSYS]<dd>
The
<i>lio_listio()</i>
function is not supported by this implementation.

</dl>
<p>
In addition to the errors returned by the
<i>lio_listio()</i>
function, if the
<i>lio_listio()</i>
function succeeds or fails with errors of
[EAGAIN], [EINTR], or [EIO],
then some of the I/O specified by the list may have been initiated.
If the
<i>lio_listio()</i>
function fails with an error code other than [EAGAIN], [EINTR], or [EIO],
no operations from the list have been initiated.
The I/O operation indicated by each list element can encounter errors
specific to the individual read or write function being performed.
In this event, the error status for each
<b>aiocb</b>
control block contains the associated error code.
The error codes that can be set are the same as would be set by a
<i><a href="read.html">read()</a></i>
or
<i><a href="write.html">write()</a></i>
function, with the following additional error codes possible:
<dl compact>

<dt>[EAGAIN]<dd>
The requested I/O operation was not queued due to resource limitations.

<dt>[ECANCELED]<dd>
The requested I/O was canceled before the I/O completed due to an explicit
<i><a href="aio_cancel.html">aio_cancel()</a></i>
request.

<dt>[EFBIG]<dd>
The 
<i>aiocbp-&gt;aio_lio_opcode</i>
is LIO_WRITE, the file is a regular file,
<i>aiocbp-&gt;aio_nbytes</i>
is greater than 0, and the 
<i>aiocbp-&gt;aio_offset</i>
is greater than or equal to the offset maximum in the open file
description associated with 
<i>aiocbp-&gt;aio_fildes</i>.

<dt>[EINPROGRESS]<dd>
The requested I/O is in progress.

<dt>[EOVERFLOW]<dd>
The 
<i>aiocbp-&gt;aio_lio_opcode</i>
is LIO_READ, the file is a regular file,
<i>aiocbp-&gt;aio_nbytes</i>
is greater than 0, and the
<i>aiocbp-&gt;aio_offset</i>
is before the end-of-file and is greater than or equal to the offset
maximum in the open file description associated with
<i>aiocbp-&gt;aio_fildes</i>.

</dl>
</blockquote><h4><a name = "tag_000_007_367">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_368">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_369">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_370">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="aio_read.html">aio_read()</a></i>,
<i><a href="aio_write.html">aio_write()</a></i>,
<i><a href="aio_error.html">aio_error()</a></i>,
<i><a href="aio_return.html">aio_return()</a></i>,
<i><a href="aio_cancel.html">aio_cancel()</a></i>,
<i><a href="read.html">read()</a></i>,
<i><a href="lseek.html">lseek()</a></i>,
<i><a href="close.html">close()</a></i>,
<i><a href="_exit.html">_exit()</a></i>,
<i><a href="exec.html">exec</a></i>,
<i><a href="fork.html">fork()</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995)
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

